ETO Development Tools 4

home *** CD-ROM | disk | FTP | other *** search

/ ETO Development Tools 4 / ETO Development Tools 4.iso / Tools - Objects / Macintosh Programmer’s Workshop / MPW QR4 / SADE 1.3b1 / sade.help < prev next >

Wrap

Text File | 1991-04-25 | 83KB | 2,459 lines

SADE 1.3 Help Summaries Help summaries are available for each of the SADE commands. To see the list of commands enter "Help Commands". In addition, brief descriptions of Variables, Constants, Expressions, built in functions, and Shortcuts are also included. To see Help summaries, Enter a command such as Help Builtins # a list of builtin (predefined) variables and functions Help commandName # information about commandName Help Commands # a list of commands Help Expressions # summary of expressions Help Patterns # summary of patterns (regular expressions) Help Shortcuts # summary of SADE shortcuts Help Variables # summary of variable references Help Basetypes # summary of basic types recognized by SADE Copyright Apple Computer, Inc. 1987-1990 All rights reserved. - Builtins Functions AddrToSource # tries to display source for a particular code address Concat # concatenate strings Confirm # confirmation dialog Copy # extract a substring from a string Eval # evaluate the contents of a string Find # find pattern in memory Length # length of a string NaN # SANE NaN (Not a Number) Request # request dialog returning string SizeOf # size of a value or type SourceToAddr # tries to give code address for a point in a source file Timer # "tick count" timer with conversion to minutes,seconds,hundreths TypeOf # type (name) of a value Undef # is a value undefined? Where # symbolic representation of an address Variables Arg[n] # n'th parameter to current Proc or Func ActiveWindow # string with pathname of topmost SADE window Date # string with current date in the form dd-mmm-yy DisAsmFormat # string controlling format of DisAsm command output Exception # number of last exception raised Inf # SANE infinity NArgs # number of actual parameters to current Proc or Func ProcessId # id of current process being debugged (an integer) TargetWindow # string with pathname of the SADE window below the topmost one Time # string with current time in the form hh:mm:ss WorksheetWindow # string with pathname of SADE Worksheet window - Commands Abort Execute Macro Shutdown AddMenu Find MoveWindow SizeWindow Alert For OnEntry SourcePath Beep Func Open Stack Begin Go Printf Step Break Heap Proc Stop Case Help Quit Target Close If Redirect Trace Cycle Kill Repeat Unbreak Define Launch Resource Undefine DeleteMenu Leave Return Untrace Directory List SadeKey Version Disasm Loop Save While Dump WindowSize Functions AddrToSource Eval Request Timer Concat Find Selection TypeOf Confirm Length SizeOf Undef Copy Nan SourceToAddr Where - Expressions The operators listed below are used in expressions in command parameters. (…) grouping @ address of † trap expression ^ pointer to . variable reference qualifier - unary negation ~ bitwise ones complement ! NOT ¬ logical NOT (¬ is Option-L) * multiplication / DIV ÷ division (÷ is Option-/) // MOD remainder + addition - subtraction << shift left >> shift right = == equal <> != ≠ not equal (≠ is Option-=) < less than <= ≤ less than or equal (≤ is Option-<) > greater than >= ≥ greater than or equal (≥ is Option->) & AND bitwise AND && logical AND XOR EOR bitwise exclusive OR | OR bitwise OR || logical OR := size compatible assignment <- arbitrary assignment Alternate spellings of several operators are provided. All of the operators are evaluated from left to right. Operators with the highest precedence are listed first, and operators in the same group have equal precedence. - Patterns - Patterns specify characters to be matched. Patterns may only be used from the Find… command in the Find menu. /entireRE/ regular expression - search forward \entireRE\ regular expression - search backward entireRE •RE regular expression at beginning of line (Option-8) RE∞ regular expression at end of line (Option-5) RE regular expression RE simpleExpr simple regular expression - defined below 'string' literal - no characters within '…' are special "string" literal - only \, ∂, {, and ` are special within '…' RE1RE2 regular expression RE1 followed by RE2 simpleExpr (RE) regular expression grouping charExpr single character regular expression - defined below simpleExpr* simple expression zero or more times simpleExpr+ simple expression one of more times simpleExpr«n» simple expression n times (Option-\, Option-Shift-\) simpleExpr«n,» simple expression at least n times simpleExpr«n1,n2» simple expression at least n1, at most n2 times charExpr character character (unless it has special meaning) ∂character character - defeats any special meaning (Option-D) ? any character except Return ≈ zero or more characters, except Return (Option-X) [charList] any character in the list [¬charList] any character not in the list (Option-L) charList ] ] first in the list represents itself - - first in the list represents itself character character charList character list of characters character-character character range (e.g. A-Z) - ShortCuts The following is a list of SADE shortcuts: Double click select word Triple click select line Double clicking before any quote (', ", or `) will select until the matching quote Double clicking before or after {}[]() will select until the matching character UpArrow move selection point one line above current selection DownArrow move selection point one line below current selection RightArrow move selection point one character to the right LeftArrow move selection point one character to the left CMD-Shift-UpArrow select text from current selection point to top of screen CMD-Shift-DownArrow select text from current selection point to bottom of screen CMD-Opt-UpArrow move selection point to top of file CMD-Opt-DownArrow move selection point to bottom of file CMD-DownArrow move selection point down to bottom of screen CMD-RightArrow move selection point to right edge of current line CMD-UpArrow move selection point to top of screen CMD-LeftArrow move selection point to left edge of current line CMD-Backspace delete from current selection to end of file In Dialogs without an Edittext item Y Yes N No CMD . Cancel - Variables VARIABLE REFERENCES There are three different types of variables -- program variables, debugger variables, and system variables. Program variables are defined in your program; debugger variables are defined during your debugging session; and system variables represent objects in the Macintosh runtime environment (e.g., registers, low-memory globals, and ROM locations). When SADE looks up a simple symbol name, it is first looked up as a debugger symbol, then as a program symbol, and finally as a system symbol. Thus, if the same name is used as a debugger symbol and as a program symbol the debugger symbol will be returned. In order to resolve such potential name conflicts SADE supports two escape characters, which may preceed an identifier to indicate whether the identifier is a program or system symbol: ` (backquote) identifies a symbol as a program symbol Δ (option j) identifies a symbol as a system symbol PROGRAM VARIABLES The simplest form of program variable reference is just the name of the variable itself. A simple reference (a single identifier) is looked up in the current name scope (CNS) as defined by where execution has stopped in the program. If execution has stopped in a particular procedure, then the variables of that procedure and the global variables in the compilation unit of that procedure will be accessible via simple references. If you need to reference a variable which is outside of the current name scope (i.e., not in the procedure where execution has been suspended or not one of the globals in the compilation unit of that procedure) then a fully qualified reference is needed. A fully qualified reference is very much like a complete file pathname describing how to get to the variable from a particular compilation unit. The syntax is: \unit [.procedure]* .variable where \ indicates that a unit name follows. In Pascal this will be the name on the UNIT or PROGRAM statement; in C or assembly this will be the name of the compilation unit's file (with ∂'s used to escape any characters not normally allowed in identifiers). The [.procedure]* indicates zero or more procedure names (more than one for nested procedures) separated by dots. This will identify the path to a variable when it is not in the current CNS. DEBUGGER VARIABLES Debugger variables are defined with the DEFINE command. These variables can be used to save values from the user program, to control debugger language contructs, etc. Debugger variables are untyped, that is, they take on the type of the value that is assigned to them (which may change the next time they are assigned to). The format of the define command is: Define [global] {declaration [':=' initialization]},… where "declaration" is a variable name followed by an optional dimension specification in square brackets, and "initialization" is a simple expression in the case of a scalar variable, or, an parenthesized list of expressions (separated by commas) in the case of an array variable. A list of values for an array may include items of the form "n of v" where "n" is an expression specifying a count and "v" is an expression specifying a particular value. Any number of variables may be declared in a single DEFINE command. The DEFINE command is not allowed inside of conditional or looping constructs. Arrays/Scalars: Scalar variables hold a value of any type. An array variable will hold up to its specified dimension of values of any type; these values may be heterogeneous, that is, they need not be of the same type. Scope: Variables which are defined outside of PROCs or FUNCs are global, and are accessible both inside and outside of PROCs. Variables which are defined inside of PROCs and FUNCs are local and have a lifetime limited to the particular activation of the PROC or FUNC, unless the optional "global" keyword was specified in the DEFINE command. - Basetypes The following basic types are recognized by SADE. They are grouped in order of increasing size or related category: Boolean # 1 byte Pascal boolean (bit 0 = 0 ==> false; 1 ==> true) UnsignedByte # Unsigned byte Byte # Signed byte Cchar # Character byte UnsignedWord # Unsigned word (2 bytes) UnsignedShort # Same as UnsignedWord Word # Signed word Short # Same as Word Integer # Same as Word Pchar # Pascal character word (low byte contains character) PascalChar # Same a Pchar UnsignedLong # Unsigned long (4 bytes) UnsignedInt # Same as UnsignedLong Long # Signed long Int # Same as long LongInt # Same as Long PString # Pascal variable length string CString # C null-terminated string AsIsString # As-is string (Packed array of char) Real # Floating point single precision (4 bytes) Float # Same as Real Single # Same as Single Double # Floating point double precision (8 bytes) Extended # Floating point extended precision (10 bytes) Extended12 # MC68881 floating point extended precision (12 bytes) Comp[utational] # Floating point computational integer (8 bytes) - Abort -stop break action and cancel pending commands Syntax abort Description The Abort command terminates the current break action and returns you to SADE, canceling all pending commands. This means that if current execution is within a structured statement (Begin...End, for instance), or if multiple commands are selected, these pending commands are not executed. To terminate a break action without canceling pending commands, see the Stop command. Example #-- Establish target, suspending application #-- and re-entering SADE at main.(1) directory 'VolName:some:path:toProg:' target 'MyProg' break \MyProg.main.(1) launch 'MyProg' #-- Break action examines the current event type #-- (assumes the event record is named myEvent) #-- For mouseDown, show co-ordinates of mouseDown and stop. #-- (Quitting break action but executing rest of pending SADE commmands) #-- For keyDown, abort. (Quitting break action AND rest of commands) #-- For any other event, show event type and continue executing #-- (By default, break actions end with an implicit go) proc EventFilter define global mouseAt; if myEvent.what = 1 then # mouseDown event mouseAt := myEvent.where; stop; elseif myEvent.what = 3 # keyDown event "keyDown"; abort; else printf "Event type %d: \n", myEvent.what; printf; end end Begin break _getNextEvent from applzone..applzone^ EventFilter go printf "Mouse down at H: %d\n V: %d\n", mouseAt.h, mouseAt.v; end #-- output Event type 0: Event type 8: Event type 6: Mouse down at H: 208 V: 144 #-- with same break action in place, restart target. go #-- output Event type 6: keyDown See also Break, Stop - AddMenu -create a menu or add menu items Syntax addmenu [ menuname [ itemname [ command ] ] ] Description The AddMenu command lets you create menus and add menu items to execute SADE commands. Menuname, itemname, and command are all string expressions and must be enclosed in quotation marks if they are string constants. If a menu of menuname does not exist, a new menu is created. If a menu item with the specified itemname already exists, it's replaced; otherwise a new menu item is created. You can include a Command-key equivalent for the item by listing the command key after a slash (/) at the end of the string. If itemname or command are not specified, AddMenu returns the current value from the specified level down. For instance, if itemname is specified without any commands, AddMenu displays the command that's currently defined for that menu item. If menuname is omitted as well, SADE returns the current values for all user-defined menus and menu items. Examples addmenu 'Debug' 'Disasm/1' 'disasm' addmenu 'Debug' 'Code Resources' 'heap restype "CODE"' See also DeleteMenu - AddrToSource (addr [,bool]) Returns 1 (true) or 0 (false) indicating whether it was able to display the source (file) statement corresponding to a particular code address. The optional boolean expression controls whether the window is brought up as the topmost (active) window. The default (when the boolean is false or omitted) is for the source window to be displayed behind the topmost window (where the command with the AddrToSource function was likely to have been issued from). Note that source windows brought up by the AddrToSource function are read-only. - Alert -display an alert box Syntax alert [ beep ] message Description The Alert command displays an alert box containing the specified message. Message is a string expression and must be enclosed in quotes if it's a string constant. The alert is displayed until the OK button is clicked. If beep is specified, a sound is generated when the alert box appears. Example if length(str) > 64 then alert "string longer than expected" end See also Beep - Beep -generate tones Syntax beep [ notespecs ] where notespecs is a string of the form [ note [,duration [,level ] ] ... ] Description For each notespec, the Beep command produces the given note for the specified duration and sound level. Multiple notespecs are separated by blanks or tabs. If no notespecs are given, a simple beep is produced. Note is one of the following: n A number indicating the count field for the square wave generator, as described in the Summary of the Sound Driver chapter of Inside Macintosh. n A string in the following format: [n ] letter [ # | b ] where n is an optional number indicating the octaves below or above middle C, followed by a letter indicating the note (A-G) and an optional sharp (#) or flat (b) character. The optional duration is given in sixtieths of a second. The defualt duration is 15 (one-quarter second). The optional sound level is given as a number from 0 to 255. The default level is 128. Example beep "2C,20 '2C#,40' 2D,60" #-- Play the 3 notes specified: C, C sharp, and D, all two octaves above #-- middle C, for one-third, two-thirds, and one full second, #-- respectively. Note that the second parameter must be quoted; #-- otherwise,the sharp character would indicate a comment. See also Alert - Begin ...End -group commands Syntax begin commands end Description The Begin...End construct allows a sequence of commands to be grouped together or bracketed. One use of this construct is to specify a breakpoint action consisting of multiple commands or procedure calls. Example break DisplayString.(4) begin str := theStr^ # save value of parameter in variable str if str = '***' then stop end end - Break -set breakpoints Syntax break addr ,... [ break-action ] or break trap [ from addr-range ] ,... [ break-action ] or break trap-range [ from addr-range ] ,... [ break-action ] or break all traps [ from addr-range ] [ break-action ] or break class <classname> [ break-action ] or break overload <functionname> [ break-action ] Description The Break command sets one or more breakpoints within a target program's code. There are two types of breakpoints: address breakpoints and trap breakpoints. Both kinds of breakpoints may be followed by a break action, a command (or series of commands) that's executed when the breakpoint is reached. You can set an address breakpoint anywhere within your program by specifying a RAM address. You can also use symbolic references, in which case the code need not be in memory at the time the breakpoint is set. Trap breakpoints can be set on a single trap, a range of traps, or on all traps. Traps can be specified by either trap name or trap number. Trap numbers must be prefixed with the trap character (*) and trap names must be preceded by an underscore (_InitGraf, for example). You can also specify a memory range, in which case SADE breaks only when the trap is called from the specified range. The same trap may be specified in multiple break commands; you can use the List command to see what breakpoints have been set. When implementing trap breakpoints, SADE first looks for a call that matches a specified trap name, checking the address range if one was given. If no match is found, SADE then looks for trap ranges containing the trap. SADE takes the most recently defined range containing the trap, again checking the address range if one was specified. Note: If you set an address break on an instruction that is a trap call for which a trap break has already been set, the address break is recognized and the trap break is not. If a break action is specified, SADE resumes program execution after executing the command(s). There are two ways to suspend program execution as part of a break action. The Abort command returns to SADE immediately, canceling any pending commands. The Stop command executes any pending commands and then returns to SADE. Warning: The commands specified in the breakpoint action are saved and are not interpreted until the breakpoint is reached. You should be sure that program symbol references will be correctly interpreted at the time the breakpoint is reached. In other words, a reference may be fine at the time you define a break action, but be out of scope when the action is actually executed. Note: If no break action is specified and the execution command (Go, for instance) just prior to hitting a breakpoint is part of a structured statement (such as While...End), or if multiple commands were selected, the remaining commands are executed after hitting the breakpoint and re-entering SADE. You can specify multiple breakpoints, separated by commas, with a single Break command. If this command includes a break action at the end, the action is applied to all breaks on the list. The class keyword causes SADE to search for all symbols that match the C++ mangled pattern created for member functions of the specified class, and for all symbols that match the Object Pascal method naming convention for the specified class. Breakpoints are then set on all routines that are named by these symbols. The overload keyword causes SADE to search for all symbols that match the C++ mangled pattern created for functions of the specified name, and for all symbols that match the Object Pascal method naming convention for the specified function name. Breakpoints are then set on all routines that are named by these symbols. Examples break _GetResource break *$A997..*$A9A0 break all traps from myproc.(1)..myproc.(5) break all traps from applZone..applZone^ #-- The following example sets multiple breakpoints. Break procB.(1), _LineTo from procA.(1)..procA.(1000), _setPort Begin;"hit one"; end list break procB.(1) # $586398 # processID =5 # has break action _LineTo # processID =5 # *$A891 # called from procA.(1) .. procA.(83) # has break action _SetPort # processID =5 # *$A873 # has break action #-- A break set on top of a matching breakpoint replaces the older one. #-- Breakpoints match if they are set on the same address or trap and #-- the called from address range, if there is one, matches. Break procB.(1) break _lineTo list break procB.(1) # $586398 # processID =5 _LineTo # processID =5 # *$A891 _LineTo # processID =5 # *$A891 # called from procA.(1) .. procA.(83) # has break action _SetPort # processID =5 # *$A873 # has break action See also Abort, List, Stop, Trace, Unbreak - Case -change case sensitivity Syntax case on | off Description By default, case sensitivity is on, which means that when looking up symbols, SADE first performs a case-sensitive lookup. If the symbol isn't found, SADE converts all the characters to uppercase and looks again. C programmers will want case sensitivity turned on. Pascal programmers, however, may want to set case sensitivity off; SADE then converts all symbols to uppercase before any lookup, speeding up the search process. Examples #-- C programmers case on CFunction CFunction.(0) CFUNCTION ### Could not find "CFUNCTION" as a program symbol case off CFunction ### Could not find "CFunction" as a program symbol #-- Pascal programmers case on PascalProc PASCALPROC.(0) PASCALPROC PASCALPROC.(0) case off PascalProc PASCALPROC.(0) - Close -close a file Syntax close [ all | windowName ] Description The Close command closes the specified file or all files. WindowName is a string expression and must be enclosed in quotation marks if it's a string constant. If no parameters are given, Close closes the target window. Note, however, that the SADE Worksheet file cannot be closed. If the contents of a file have not been saved, a dialog box asks whether they should be. Examples close 'myFile' close targetWindow #no quotes needed--uses SADE variable TargetWindow - Concat (str [,str…]) Returns the concatenation of its string arguments. - Confirm (msg [,bool]) Displays confirmation message in a dialog box and returns user response. If the bool argument is omitted or if bool = 0, then Confirm presents an Ok/Cancel dialog, and returns 1 for Ok and 0 for Cancel. If bool <> 0, then Confirm presents a Yes/No/Cancel dialog and returns 1 for Yes, 0 for No and -1 for Cancel. - Copy (str, start, length) Returns the substring of its first string argument, starting at the specified character position, with the specified length. - Cycle -continue execution within construct Syntax cycle [ if Boolean ] Description The Cycle command causes execution to continue from the conditional test of a While, Repeat, or For construct, or from the beginning of a Loop construct. If a Boolean expression is specified, Cycle executes only if the expression is nonzero; otherwise execution continues immediately following the Cycle command. Example define testnum := 0 define endnum := 6 define cycleMax := 4 repeat printf "testNum = %d\n", testNum testNum := testNum + 1 cycle if testNum < cycleMax "\nDidn't cycle" until testNum = endNum #-- output testNum = 0 testNum = 1 testNum = 2 testNum = 3 Didn't cycle testNum = 4 Didn't cycle testNum = 5 Didn't cycle See also Leave - Define -declare a SADE variable Syntax define [ global ] declaration [,...] where declaration has the form name [ dimension ] [ := init-value | = init-value ] where name must be unique in the current scope unless declared global. dimension is an expr enclosed in brackets [ ] init-value is either an expr for the initial value of simple types, or a list of the following form for structured types: ( [ expr of ] init-value , ..) where the optional of clause allows for replication of a value. Description The Define command defines one or more SADE variables. A variable must be defined before it's used. The variable declaration identifies the name, scope, and (optionally) the initial value of the variable. Multiple declarations must be separated by commas. SADE variables are dynamically typed; that is, their type is determined on assignment (and may be changed by new assignments). SADE variables defined as arrays require an index. SADE array variables may contain a heterogeneous set of values; that is, the elements may contain values of different types. An initial value for simple types may optionally be specified by an expr following the assignment operator (:=) or, in this case only, (=). If the declared item is an array, a list of initial values may be specified as the values of the array elements. The scope of a variable can be either global or local. If a variable is defined outside a procedure (or function), its scope is automatically global. In other words, it is known both inside and outside of any procedures. If a variable is declared inside a procedure, its scope is local unless the keyword global is given. If a global and a local variable exist with the same name, the local symbol overrides the global symbol. Redefining global variables replaces the previous definition, with one exception: If the definition is within a procedure, and the new definition matches the existing definition, then the existing definition is retained. For example, when a global variable is defined within a procedure or function and is given an initial value, the initialization occurs only when the variable is actually created. Subsequent invocations of the procedure do not affect the current value of the global variable, and can make use of the value left in the variable by the preceding invocation. The Define command may not be used within any structured statement. To remove a variable definition, use the Undefine command. Examples #-- define a five element array, with the first four elements true #-- and the last element false define global test[5] := (4 of 1,0) #-- define a 30 element array, with the first 29 elements true #-- and the last element false define arraysize := 30 define myArray[arraysize] := (arraysize-1 of 1,0] #-- In the next example, note that the definition of INDEX in #-- RotateLeftOneWCarry() is local to that procedure; otherwise it #-- would be attempting to redefine the global INDEX that's used #-- as a FOR loop counter when RotateLeftOneWCarry() is called. proc RotateLeftOneWCarry() define global SADEArray[4] := ("indexed by one", 2, 3.33, "fourth and last") define index define holder for index := 1 to 4 do if index = 1 then holder := SADEArray[index] else SADEArray[index-1] := SADEArray[index] if index = 4 then SADEArray[index] := holder end end end end define index define holder for index := 1 to 4 do RotateLeftOneWCarry() for holder := 1 to 4 do SADEArray[holder] end printf "\n" end undefine RotateLeftOneWCarry #-- output 2 3.33 fourth and last indexed by one 3.33 fourth and last indexed by one 2 fourth and last indexed by one 2 3.33 indexed by one 2 3.33 fourth and last See also Undefine - DeleteMenu -delete menus or menu items Syntax deletemenu [ menuname [ itemname ] ] Description The DeleteMenu command deletes menus and/or menu items. Menuname and itemname are string expressions and must be enclosed in quotation marks if they are string constants. If only menuname is specified, the entire menu is deleted. If a user-defined menu item with the specified name exists, it is deleted. The standard SADE menus and menu items cannot be deleted. Warning: If both menuname and itemname are omitted, all user-defined items are deleted. Example deletemenu "Special" "Launchapp" See also AddMenu - Directory -set or write the default directory Syntax directory [ directoryname ] Description When you first enter SADE, the default directory is the directory where SADE resides. The Directory command sets the default directory for all SADE file-oriented operations to the specified directory. Directoryname is a string expression and must be enclosed in quotation marks if it's a string constant. If directoryname isn't specified, the current default directory is displayed. Examples macro here "volume:very:long:directory:path" directory here macro RootPath "volume:very:" directory concat(RootPath, "long") See also Sourcepath - Disasm -disassemble code Syntax disasm [ addr [ count ] ] or disasm [ addr-range ] Description The Disasm command disassembles instructions starting at the location specified by addr or addr-range. The default behavior when no address is specified is to begin disassembling at the end of the last disassembly. If the value of the program counter has changed since the last disassembly, the program counter (PC) is used as the default starting address. If no range or count is specified, the number of instructions (not lines) disassembled defaults to 20. Each line of the disassembly output is divided into four fields: the module offset, the address of the instruction, the hexadecimal encoding for the instruction, and the assembly code (opcode, operand, and comment). You can modify the presence, order, and format of these fields by changing the value of the built-in variable DisAsmFormat (described in Chapter 3). Example #-- diassemble 5 instructions in standard format, starting at #-- the eighth statementof the DisplayText routine. disasm DisplayText.(8) 5 #-- output DisplayText +0040 003191A8 2F2D FE64 MOVE.L -$019C(A5),-(A7) +0044 003191AC 2F2D FE78 MOVE.L -$0188(A5),-(A7) +0048 003191B0 4EBA FE26 JSR FlushDWindow ; 00318FD8 +004C 003191B4 486D FE48 PEA -$01B8(A5) +0050 003191B8 4EBA 00C0 JSR DisplayString ; 0031927A See also Dump - Dump -display memory Syntax dump [ byte | word | long ] [ addr [ count ] ] or dump [ byte | word | long ] [ addr-range ] Description The Dump command displays memory at the location specified by addr or addr-range. If no parameter is given, the memory starting at the program counter is displayed. The memory is displayed in hexadecimal and ASCII characters according to the specified format, which may be byte, word, or long. The default format is word. Remember that to dump the value of a variable "foo", you must specify dump @foo (since dump foo would take foo's value and use it as an address). Examples dump byte a5 $00146A8E 00 14 68 74 FF FF FF FF 00 00 00 00 00 00 00 00 ..ht............ dump word a5 40 $00146A8E 0014 6874 FFFF FFFF 0000 0000 0000 0000 ..ht............ $00146A9E 000E 6C66 0000 FFFF FFFF FFFF FFFF FFFF ..lf............ $00146AAE 0001 4EF9 000E 6E00 ..N...n. dump long a5..a5+40 $00146A8E 00146874 FFFFFFFF 00000000 00000000 ..ht............ $00146A9E 000E6C66 0000FFFF FFFFFFFF FFFFFFFF ..lf............ $00146AAE 00014EF9 000E6E00 00 ..N...n.. See also Disasm - Eval (str [,expr]) Returns the value of the expression contained in its string argument. If an optional second argument is specified, it will be returned if Eval encounters any errors in its evaluation; otherwise, if there was no second argument errors during evaluation will be reported as usual (and will terminate command processing). Example #-- The following line tells you that main.(0) is an addressable symbol eval('main.(0)') main.(0) #-- However, your program probably does not have xyz defined. eval('xyz.(0)') ### Could not find "xyz" as a program symbol #-- If you want to supress the error message, invoke eval with a second argument. #-- You can check for the second argument in a script. if eval('xyz.(0)','????') = '????' then printf "Eval failed.\n" end Eval failed. - Execute -execute commands in a file Syntax execute filename Description The Execute command executes the commands and definitions contained in the specified file. Filename is a string expression and must be enclosed in quotation marks if it's a string constant. The Execute command can't be used within a structured statement. Example #-- In this example, the Redirect command creates a file to hold #-- output from SADE. Entering a string echos the string. That #-- output is redirected to the file, becoming the file's contents. #-- Here the string is a comment and a SADE command to execute #-- the contents of the next file in the chain. open 'exec1' redirect 'exec1' '"\n executing exec1 now"' "execute 'exec2'" open "exec2" redirect 'exec2' "'now executing exec2'" "execute 'exec3'" open "exec3" redirect 'exec3' '"Done in exec3"' redirect pop all execute "exec1" Alert "Try a tile windows here\n_ Then look at the worksheet for output" #-- output executing exec1 now now executing exec2 Done in exec3 - Find -search for a target Syntax find [ count ] target [ ,n ] [ addr-range [ mask mask ] ] or find [ count ] target [ ,n ] [ addr [ count ] [ mask mask ] ] Description The Find command searches memory for a target pattern, which can be either a numeric or string expression. If you specify the count keyword, Find tells you how many occurences of the target it found. If you omit the count keyword, Find displays the address of the first occurrence of the pattern. You can use the n parameter to specify which occurrence of the pattern you want; for instance, if you specify 3 for n, Find returns the address of the third occurrence of the pattern. You may start the search at a specified addr and look up to count bytes beyond, or you may limit the search to addr-range. The default range is the MultiFinder block containing the application's heap and stack (in other words, all of the memory that belongs to the application). The mask parameter (prefaced by the mask keyword) is an optional numeric or string expression that is logically ANDed with the contents of each memory location before the comparison is done. Important: Remember that expression values in SADE are long words by default; to specify another size, use typecasting, as shown below. Examples dump $20 $40 $00000020 0027 A002 0027 A00A 0040 1F52 0027 A012 .'...'...@.R.'.. $00000030 0027 A01A 0027 A032 0040 113C 0027 A02A .'...'.2.@.<.'.* $00000040 0040 113C 0040 113C 0040 113C 0040 113C .@.<.@.<.@.<.@.< $00000050 0040 113C 0040 113C 0040 113C 0040 113C .@.<.@.<.@.<.@.< #-- Looking for the number of occurances of target, #-- from start address, for number of bytes. #-- Target is cast to word size. The default size would #-- be long and nothing in this range matches $0000113C. find COUNT (word)$113C $20 $40 9 #-- Looking for first occurance of target, in address range. #-- C style type cast to limit the target to word size. find (word)$113C $20..$96 $0000003A #-- Looking for second occurance of target. #-- Using Pascal style typecast on target. find word($113C), 2 $20 $40 $00000042 #-- Looking for a long. #-- Masking the memory searched prior to the compare. find $0000113C $20..$96 MASK $0000ffff $00000038 #-- Match same last target with same last mask. #-- Just change the address range to search. find SAME $40..$50 $00000040 - For ...End -loop with a control variable Syntax for clause [ do ] commands end where clause may have one of the following forms: var := expr to expr var := expr downto expr var := expr , ... Description The For...End construct provides looping with a control variable. The enclosed commands are executed until the control variable has taken on each successive value in the range expressed by clause. The control variable var must be declared before it can be used, and array variables are not allowed. For the clause expr to expr, the commands are executed and the control value incremented once for every integer value in the range. For the clause expr downto expr, the control value is decremented. The third clause is a list of expressions; execution continues until the control variable has taken the value of each of the listed expressions. For...End constructs may be nested; they may also be used within other flow-control constucts, as well as in break actions. The control variable may be modified within the body of the loop (but cannot, of course, be shared between nested constructs). Example define var := 0 define outerLooper, syncopation for outerLooper := 3 downto 1 do "\n" for syncopation := "one","two","three", var printf "%d -- " , outerLooper syncopation var := var + 1 end end #-- output 3 -- one 3 -- two 3 -- three 3 -- 0 2 -- one 2 -- two 2 -- three 2 -- 4 1 -- one 1 -- two 1 -- three 1 -- 8 - Func ...End -define a SADE function Syntax func name [ ( arg-name ,... ) ] commands end Description SADE functions are delimited by the Func...End construct. The last statement to be executed must be a Return command specifying a return value. The type of a function is not specified in the definition but rather takes on the type of the value returned. (Thus functions are not limited to returning results of a single type.) SADE functions use conventional calling notation, with the function name followed by a list of parameters enclosed by parentheses. Function parameters are handled in the same fashion as procedure parameters, and the predefined SADE variables Arg and NArgs may be used. (See the description of the Proc command for an example using these variables.) User-defined functions may be called anywhere an expression is allowed. Example func fact(n) if n <= 1.0 then return 1.0 else return n * fact(n-1) end end See also Proc, Return - Go -resume execution Syntax go [ til addr ,...] or go [ while expr ] or go [ until expr ] Description The Go command resumes program execution at the current program counter. If you specify the keyword til, SADE sets a temporary breakpoint at the specified address(es). When the breakpoint is encountered, SADE is reentered and the breakpoint is removed. Note that if multiple breakpoints are specified with the keyword til, all breakpoints are removed when any of them is reached. If the address is in ROM, SADE informs you that it can't set a breakpoint in ROM. If a conditional expression is specified, SADE uses trace mode until the condition is met (for the keyword until) or broken (for the keyword while). Examples go til \OtherCompilationUnit.myProc.(1) go while particularVar < 2 go until ProgVar[1] = 3 See also Stop - Heap -display, check, or total heap information Syntax heap [ display ] [ addr ] [ blocktype ] heap check [ addr ] heap totals [ addr ] [ blocktype ] Heap Display Description The Heap command displays information about the specified heap. You can specify a heap that starts at addr; if no address is specified, the heap pointed to by the global variable theZone is displayed. By default, this information is displayed: • a dot if the object is locked or nonrelocatable • the block length • the block type (relocatable, nonrelocatable, free) • the address of the beginning of the block • block attributes (locked, resource, purgeable) • the address of the master pointer if it's a relocatable block • for standard toolbox data structures, a description of the structure • for a resource, the resource type and ID, and the reference number of the file it's in You can specify one of the following blocktypes to limit the display to a particular type of block: • purge[able] limits the display to purgeable blocks. • nonreloc[atable] limits the display to nonrelocatable blocks. • reloc[atable] limits the display to relocatable blocks. • free limits the display to free blocks. • lock[ed] limits the display to locked blocks. • res[ource] limits the display to resources. • restype type limits the display to the specified resource type. Note that type is case-sensitive and should be enclosed in single quotation marks ('MENU', for example). Example Heap restype 'MENU' #-- output BlkAddr BlkLength Typ MasterPtr Flags RType RId RFRef RName $00316590 $00000098 H $0031452C R MENU 1000 $0584 "File" $00316838 $00000050 H $00314528 R MENU 1001 $0584 "Edit" $00316888 $000000F4 H $00314524 R MENU 1002 $0584 "Log" Heap Check Description The Heap Check command checks the consistency of the current application heap, which is by default the heap referenced by the global variable theZone. You can specify another heap, but addr must be the address of the heap zone header. (In other words, you can't check part of a heap.) Heap Check performs range checking to make sure all pointers are even and non-NIL, and that block sizes are within the range of the heap. It verifies that the self-relative handle points to a master pointer referring to the same block. For nonrelocatable blocks, it checks if the heap zone pointer points to the zone where the block exists. Heap Check also verifies that the total amount of free space is equal to the amount specified in the header, and that all pointers in the free master pointer list are in the heap. Examples Printf "Checking %P's heap at $%.08X\n", ^Pstring( $910)^, TheZone Heap Check TheZone Printf "Checking the System heap at $%.08x\n", SysZone Heap Check SysZone Printf "Checking the Multifinder heap at $%.8x\n", **$2a6+$c Heap Check $2a6^^+$c #-- output Checking SADE's heap at $00146EF2 The heap is okay. Checking the System heap at $00001400 The heap is okay. Checking the Multifinder heap at $00023d64 The heap is okay. Heap Totals Description The Heap Totals command summarizes the state of the current application heap, which is by default the heap referenced by the global variable theZone. You can specify another heap that starts at addr. Information is given for free, nonrelocatable, and relocatable objects. If you wish to restrict the display to a particular type of block, you can specify one of the following blocktypes: • purge[able] limits the display to purgeable blocks. • nonreloc[atable] limits the display to nonrelocatable blocks. • reloc[atable] limits the display to relocatable blocks. • free limits the display to free blocks. • lock[ed] limits the display to locked blocks. • res[ource] limits the display to resources. • restype type limits the display to the specified resource type. Note that type is case-sensitive and should be enclosed in single quotation marks ('CODE', for example). Example heap totals #-- output Total Blks Total Size Free 23 49080 Nonrelocatable 7 1348 Relocatable 89 21232 Locked & NonPurgeable 2 5796 Locked & Purgeable 2 8136 UnLocked & Purgeable 6 680 UnLocked & NonPurgeable 79 6620 Heap (total) 119 71660 - Help -display help information Syntax help [ identifier ,... ] help Expr(expression) Description The Help command displays information about using SADE, including the syntax of all SADE commands. To see what values identifier can have, just enter help. The first form takes unquoted tokens which represent names of command, functions, variables, etc. The second form takes an expression which will be evaluated to yield the name about which to get help information. - If ...End -conditional execution of commands Syntax if Boolean [ then ] commands [ elseif Boolean [ then ] commands ] ... [ else commands ] end Description The If...End construct allows for conditional execution of sequences of SADE commands. Each if must be concluded by a corresponding end. Elseif and else are optional, but must appear between the if and end in the order indicated above. More than one elseif may appear, but at most one else may appear. The commands controlled by an if extend to the corresponding end, or to the first corresponding elseif or else. The commands controlled by an elseif extend to the next corresponding elseif, else, or end. The commands controlled by an else extend to the corresponding end. When an If...End construct is evaluated, if the if Boolean is true, the statements controlled by the if are executed and the remainder of the construct to the end is skipped. If the Boolean is false, the statements controlled by the if are skipped and the next (elseif) condition is checked, if present. If an elseif condition is evaluated and is true, the commands it controls are executed and the remainder of the construct is skipped. If no conditions are evaluated as true, when the else command is reached (if present), the commands controlled by the else are executed (otherwise, they're skipped). If...End constructs may be nested. Example #-- Steps through a five element array using a low to high index, #-- looking for first true element, and resetting it to false. #-- Done 5 times, starting with the first four elements true #-- and the last element false. define global test[5] := (4 of 1,0) proc IfDemo define whichtest define showMe for whichtest := 1 TO 5 do printf "\n" for showMe := 1 to 5 do printf "%t", test[showMe] end printf " - " if test[1] "test[1] true" elseif test[2] "test[2] true" elseif test[3] "test[3] true" elseif test[4] "test[4] true" elseif test[5] "test[5] true" else "all tests false" end test[whichtest] := 0 end end IfDemo #-- output 11110 - test[1] true 01110 - test[2] true 00110 - test[3] true 00010 - test[4] true 00000 - all tests false - Kill -kill an application Syntax kill filename Description If you want to terminate an application, (whether it's suspended or not), use the Kill command. Be aware, though, that Kill is dangerous, since it doesn't give the unlucky application a chance to perform its usual exit routines (like saving data). Kill does perform cleanup activities like freeing the MultiFinder memory occupied by the application and removing its trap patches. Filename is a string expression and must be enclosed in quotation marks if it's a string constant. Examples kill 'VolName:full:path:to:targetProg' define RootPath := "VolName:full:" kill Concat(RootPath, "path:to:targetProg") directory 'VolName:full:path:to:' kill "targetProg" - Launch -launch an application Syntax launch [filename] Description The Launch command launches the specified application. Filename is a string expression and must be enclosed in quotation marks if it's a string constant. Launch does nothing if the file type of the specified file is not 'APPL'. If no filename is specified, the current target is launched. Launching an application that is already executing is the same as executing the go command. Examples #-- define directory location for target program sources #-- (if not in the same directory as the program file) sourcepath 'VolName:path:targetProg:sources:' #-- define directory location of target program executable file #-- and, if different, the location of its .sym file target 'VolName:path:targetProg' using 'VolName:path:targetProg.sym' #--- then launch the target progam, as in the examples below, #--- SADEKey to suspend and begin debugging it. launch 'VolName:path:targetProg' #-- or define RootPath := "VolName:" launch Concat(RootPath, "path:targetProg") #-- or directory 'VolName:path:' launch "targetProg" see also Target - Leave -exit from a looping construct Syntax leave [ if Boolean ] Description The Leave command lets you exit from a Loop, While, Repeat, or For construct. You can specify a condition for leaving with the if keyword. Example define testnum := 0 repeat Printf "testNum = %d\n", testNum leave if testNum = 3 testNum := testNum + 1 until testNum = 6 Printf "after leaving Repeat loop - testNum = %d\n", testNum #-- output testNum = 0 testNum = 1 testNum = 2 testNum = 3 after leaving Repeat loop - testNum = 3 See also Cycle, For, Loop, Repeat, While - Length (str) Returns the length of its string argument. - List -list processes, tracepoints, and breakpoints Syntax list process or list trace [ traps | addrs ] or list break [ traps | addrs ] Description The List command lets you see what processes, breakpoints, and tracepoints are around. For processes, the display includes the following information: a process number, a "loaded" or "not-loaded" designation, and the filename and symbol filename (typically the filename followed by .SYM) for the process. For breakpoints and tracepoints, List displays the location along with its symbolic representation. The optional traps or addrs keywords limit the display to trap or address breakpoints (or tracepoints) respectively. Examples list break # list all breakpoints set #-- output EVENTLOOP.(5) # $21A4E2 # processID =10 # has break action EVENTLOOP.(11) # $21A500 # processID =10 EVENTLOOP.(2) # $21A4C4 # processID =10 list process #-- output Process# Loaded? FileName, SymbolFile 6 Loaded SADE, SADE.SYM 2 Loaded Finder, Finder.SYM See also Trace, Break - Loop ...End -repeat commands until Leave Syntax loop commands end Description The Loop...End construct provides unconditional looping. The enclosed commands are executed repeatedly. To exit the loop, use the Leave command. Loop constructs may be nested. Example define Inner := 0 define Outer := 0 loop loop Inner := Inner + 1 printf "Inner: %d " , Inner leave if Inner > Outer end Inner := 0 Outer := Outer + 1 printf "Outer: %d\n", Outer leave if Outer > 4 end #-- output Inner: 1 Outer: 1 Inner: 1 Inner: 2 Outer: 2 Inner: 1 Inner: 2 Inner: 3 Outer: 3 Inner: 1 Inner: 2 Inner: 3 Inner: 4 Outer: 4 Inner: 1 Inner: 2 Inner: 3 Inner: 4 Inner: 5 Outer: 5 See also Leave - Macro -define a macro Syntax macro name string-expr Description The Macro command associates a string of characters with a name. Macros let you define short, familiar names to use instead of long, unfamiliar strings. For instance, the SADEStartup file defines macros that let you use MacsBug-like syntax for certain SADE commands. Macro definitions can be nested; that is, they can contain references to other macros. Macro definitions cannot be recursive, however; in other words, a macro definition can't reference itself. Macro definitions are not allowed in structured statements. Macros may be redefined. Macro definitions are limited to a length of 254 characters. Examples macro br 'break' macro clr 'unbreak all' macro dir "volume:very:long:directory:path" directory dir - NaN (n) Returns the NaN (Not a Number) with the specified value. - OnEntry -set commands for SADE entry Syntax onEntry [ break-action ] Description The OnEntry command supplies commands that are to be executed each time SADE is entered. Each OnEntry command replaces the commands specified by the previous OnEntry command. In the SADEStartup file, the StandardEntry procedure is specified as an OnEntry break action. You can define your own OnEntry actions in the SADEUserStartup file, but you'll probably want to use the one in SADEStartup as a model (so as not to lose the operations it performs). The OnEntry command accepts only one command or procedure invocation. If you want to execute multiple commands and/or procedures upon entry, use the Begin..End construct to group them. See also Break, Begin - Open -open a file Syntax open [ source ] [ behind ] filename Description The Open command opens the specified file. Filename is a string expression and must be enclosed in quotation marks if it's a string constant. The file must be of type 'TEXT'. The source keyword opens the window read-only. If you specify behind, the window is opened just behind the frontmost SADE window, otherwise, it's opened as the frontmost window. Example open 'myFile' See also Close, Save - Printf -print formatted output Syntax printf [ format [ , argument ] ... ] or printf [ (format [ , argument ] ... ) ] Description The Printf command is the most complicated of the SADE commands. If you find its myriad options intimidating, remember that Printf has one simple and important use: printing anything you want to a SADE window or file. You can also use Printf to convert and format values in just about any way you might want. Format is a string containing characters to print, as well as format specifications for arguments that follow. Format specifications are preceded by the % character. For instance, to print the value of the variable myVar as a decimal number, along with a message, enter: printf "The value of myVar is %d" myVar Each format specification applies to zero or more arguments. When the format specifications are exhausted, any remaining arguments are ignored. Likewise, when the specified arguments are exhausted, any remaining format specifications are ignored. Examples #-- Displays record definition of system type EventRecord. #-- Notice how EventRecord.Where, which is of type Point, has been #-- expanded to show its definition too. printf "%P", ^pstring($910)^ myProg printf "%P", *(pstring*) $910 myProg printf "%-t", EventRecord RECORD WHAT: Word; MESSAGE: Long; WHEN: Long; WHERE: RECORD CASE Word OF (1): (RECORD V: Word; H: Word; END); (2): (RECORD VH: ARRAY [(0, 1)] OF Word; END); END; MODIFIERS: Word; END #-- Doing the same thing with a target program variable #-- of type EventRecord. The %t format specifier lets #-- the Printf display format be controlled by the #-- type of the variable displayed. typeof(myEvent) EVENTRECORD printf "%t", myEvent RECORD WHAT: 3; MESSAGE: 16686; WHEN: 284053; WHERE: RECORD CASE Word OF (1): (RECORD V: 272; H: 267; END) (- - -); END; MODIFIERS: 2432; END - Proc ...End -define a SADE procedure Syntax proc name [ arg-name ,... ] commands end or proc name [ ( arg-name ,... ) ] commands end Description SADE procedures are delimited by the Proc...End construct. The procedure name is followed by an optional parameter list; if present, the list identifies parameters by name only. Parameters are not assigned a type but instead take on the types of the actual parameter values when the procedure is called. The parameter list may optionally be enclosed in parentheses. If the parentheses are included in the definition, they must also be used when the procedure is called (and vice versa). The number of actual parameters need not match the number of formal parameters in the definition. If too few actual parameters are specified, the formal parameters for which there were no corresponding actual parameters are assigned a special undefined value. Extra actual parameters have no corresponding formal name but can be referenced through the predefined SADE variable Arg, which lets you access the parameters of a procedure with references of the form arg[n]. The number of the last actual parameter specified is contained in the predefined SADE variable NArgs. Note that the values of these variables represent the parameter state of the currently active procedure and are not defined outside it. Procedures may be redefined. A procedure must be defined before a call to it can be processed. If you want mutually recursive procedures, a "dummy" procedure (similar to a Pascal FORWARD definition) must first be defined. A second procedure can then redefine the first one, referencing the second procedure. The minimal dummy procedure definition is: proc foo; end. Procedure calls may be nested. Example #-- This procedure illustrates the use of the #-- Arg(n) and Nargs built-in SADE variables proc myProc (arg1, arg2, arg3, arg4) define looper "in myproc" printf( "called with nargs: %d \n", nargs) for looper := 1 to nargs printf ("arg %d: %d \n", looper, arg[looper]) end "\n" end "call myproc with 1 arg" myproc(1) "call myproc with 2 args" myproc(1,2) "call myproc with 3 args" myproc(1,2,3) "call myproc with 4 args" myproc(1,2,3,4) #-- output call myproc with 1 arg in myproc called with nargs: 1 arg 1: 1 call myproc with 2 args in myproc called with nargs: 2 arg 1: 1 arg 2: 2 call myproc with 3 args in myproc called with nargs: 3 arg 1: 1 arg 2: 2 arg 3: 3 call myproc with 4 args in myproc called with nargs: 4 arg 1: 1 arg 2: 2 arg 3: 3 arg 4: 4 See also Func - Quit -quit SADE Syntax quit Description The Quit command terminates SADE and passes control to another process as determined by MultiFinder. Be aware that Quit kills any suspended applications. See also Shutdown - Redirect -redirect output Syntax redirect [ append ] filename or redirect [ pop ] [ all ] Description The Redirect command redirects the output from SADE commands to the specified file. The simplest way to use redirection is to replace the contents of the named file. If you specify the append keyword, the output is appended to the end of the file. You can also use the S character (Option-6) to replace or append to the selection in an open window (see the example below). Warning: Be aware that if you use use Redirect to replace the contents of a file that's not open, there's no way to undo it. (If the file is open, you can close it and respond "No" when the dialog asks whether to save changes.) You can nest Redirect commands to as many as 10 different files; SADE maintains the names of these files as a last-in, first-out queue. If you use the pop keyword, or if you use no parameters at all, the output from SADE commands is redirected to the file at the head of the queue. If all or pop all is specified, standard output is redirected to the current command window. Note: Any error conditions cause SADE to perform an implicit pop all for any redirected files; this ensures that output returns to the current command window. Examples redirect "whyNot.S" # Replace the current selection #-- In the next example, the Redirect command creates a file to hold #-- output from SADE. Entering a string echos the string. #-- That output is redirected to the file, becoming #-- the file's contents. #-- Here the string is a comment and a SADE command to execute #-- the contents of the next file in the chain. open 'exec1' redirect 'exec1' '"\n executing exec1 now"' "execute 'exec2'" open "exec2" redirect 'exec2' "'now executing exec2'" "execute 'exec3'" open "exec3" redirect 'exec3' '"Done in exec3"' redirect pop all execute "exec1" Alert "Try a tile windows here\n_ Then look at the worksheet for output" #-- output executing exec1 now now executing exec2 Done in exec3 - Repeat ...Until -conditionally repeat commands Syntax repeat commands until Boolean Description The Repeat ... Until construct provides conditional looping with a test at the end of the loop. The enclosed commands are executed until Boolean is true. The enclosed commands are executed at least once. Repeat constructs may be nested. Example target 'MyProg' break \MyProg.MainEventLoop.(1) launch 'MyProg' #-- hasEvent is a global variable in MyProg initialized to 0 printf "Pc at %t \nEventReceived? %t \n", where (pc), hasEvent define dummy repeat step dummy := addrtosource(pc, 1) until hasEvent printf "\nPc at %t \nEventReceived? %t \n", where (pc), hasEvent #-- output Pc at MAINEVENTLOOP.(1) EventReceived? FALSE Pc at MAINEVENTLOOP.(32) EventReceived? TRUE See also Leave - Request (msg [,default]) Displays a request dialog box with the specified message (with an optional default response) and returns the user response. If the user cancels, Request will return the string '_CANCEL_'. - Resource -display the resource map Syntax resource [ display ] [ addr ] [ restype 'type ' ] resource check [ addr ] Resource Display Description The Resource command displays the contents of your application's resource maps and the system resource map. If you want to display only a particular map, addr should be the address of the map. The information displayed for each map includes: its location, the resource ID, the resource type, the value of the master pointer, whether the resource is locked or unlocked, and the resource name. If a resource isn't loaded, the master pointer field says "not loaded." You can also restrict the display to a particular resource type by using the restype keyword with the desired type. Note that type is case-sensitive and should be enclosed in single quotation marks ('WIND', for example). Example resource restype 'WIND' #-- output Resource Map at $00316EF8 ResId RType MasterPtr Locked? Name 1000 WIND $00316BE4 Unlocked 1001 WIND $00316C08 Unlocked 1002 WIND $00316484 Unlocked 1003 WIND $003164B8 Unlocked 1004 WIND $003164D8 Unlocked Resource Map at $0002B19C ResId RType MasterPtr Locked? Name -16000 WIND NotLoaded -15968 WIND NotLoaded -15840 WIND NotLoaded Resource Check Description The Resource Check command checks the target application's resource maps for consistency. If you want to check a particular map, addr should point to the address of the map. If an inconsistency is found, the command displays a diagnostic message specifying the problem. - Return -return from a procedure or function Syntax return [ result ] Description The Return command returns you from a procedure or function currently in execution. When returning from a function, the function result must be specified. (When returning from a procedure, there is no return value.) Example func MiscTypes (index) define global SadeArray[4] := (1, "this is two", 3.3, 4) return SadeArray[index] end define selector for selector := 1 to 4 do printf "%t \n", MiscTypes(selector) end #-- output 1 this is two 3.3 4 See also Func, Proc - SADEKey -define a key for entering SADE Syntax sadekey [ keycode ] Description The SADEKey command lets you specify a different Command-Option key combination for entering SADE. A complete list of keycodes can be found in the Toolbox Event Manager chapter of Inside Macintosh Volume V. To see what key is specified as the SADEKey, just type sadekey. Example sadekey 33 #-- define Command-Option-Delete combination as SADEKey - Save -save a file Syntax save [ all | filename ] Description The Save command saves the specified file or, if all is specified, saves all files. Filename is a string expression and must be enclosed in quotation marks if it's a string constant. If the specified file wasn't modified since the last time it was saved, Save does nothing. If no parameters are given, Save saves the target window. Example save 'myFile' See also Open, Close - Selection (windowname [,n [,m]]) Returns the text of the selection in the specified window as a string. At most 254 characters will be returned. If the optional second and third integer arguments are specified, the selection will first be set to the specified character offsets in the file. (The character indices are zero based.) - Shutdown -shut down or restart the machine Syntax shutdown [ restart ] Description The Shutdown command terminates SADE and calls the Shutdown Manager. If restart is specified, the Macintosh is restarted. Be aware that all unsaved work is lost. - SizeOf (expr) Returns the size of object specified by its expression argument. - SizeWindow -change the size of a window Syntax SizeWindow [To h,v] [windowname] Description The SizeWindow command sets or displays the size of the specified window. The argument windowname is a string expression. If it isn't specified, TargetWindow is assumed. If the To keyword is used, the window is resized to the specified horizontal and vertical dimensions. Otherwise the size of the specified window is written out. - SourcePath -tell SADE where your source files are Syntax sourcepath [ [ add | del[ete] ] directoryname , ... ] Description The SourcePath command tells SADE what directory your source files are in. If your source files are in more than one directory, you can give the SourcePath command a list. If you're unsure which directories you've specified, simply enter sourcepath and the current search path is displayed. If you want to add a directory to, or delete a directory from, the previously specified directories in the search path, you can use the add or delete keywords. Note that if you specify a directory without using the add keyword, any directories previously specified are replaced. Examples sourcepath 'srcdir', ':myotherdir' # sources in more than one directory sourcepath add ":samples" # add directory Samples to search path See also Directory - SourceToAddr (string-expr [,bool]) Returns the code address which corresponds to the location of the beginning of the selection in the window (file) specified by the string expression argument. A value of zero is returned if SADE was not able to determine what address the window selection represents. If the optional second argument is specified and is non-zero, the function will return a PString with an error message if it fails to determine the address. - Stack -display stack frames Syntax stack [ count ] [ at addr ] Description The Stack command displays a list of the stack frames for the target application. The stack frames displayed are based on register A6 or addr if at is specified. For each entry, Stack gives the address of the stack frame, the name of the procedure or function that allocated the frame, and the name and offset (if available) of the parent procedure. If an explicit count is specified, then at most that many stack frames (counting back from the current frame) are displayed. Example stack at DisplayText.(6) stack Frame Addr Frame Owner Called From <main> CMain $0032BC24 main CMain+$0028 $0032BB2C SkelMain main.(51) $0032BB0C LogEvent SkelMain.(13)+$0012 $0032BADC ReportUpdate LogEvent.(50)+$0004 $0032BACC DisplayText ReportUpdate.(1)+$0004 - Step -single step execution Syntax step [ asm | line ] [ into ] Description The Step command lets you execute your program one step at a time, from either the source code level or the object code level. If line (the default) is specified, execution proceeds one source statement at a time. If the source window containing the current line can be found, the next line to be executed is indicated. If asm is specified, execution proceeds one instruction at a time; the instruction at the program counter is executed and SADE is re-entered. Traps are always treated as single instructions; SADE steps over them, stopping at the first instruction following the trap. Subroutines called by JSR and BSR instructions can either be stepped over or stepped into. If into is specified, SADE steps in, stopping at the first instruction of the subroutine. If into is omitted, BSRs and JSRs are treated as single instructions. Warning: Don't try to step over a routine that does not return to the caller; for instance, a call to longjmp(). SADE steps over procedure and function calls by setting the trace bit until after the JSR or BSR is executed, and then replaces the return address with the address of a SADE routine. Since longjmp() restores a previously saved register set, including a new stack pointer, SADE's return is lost. If you want to go to the routine restored by longjump0, execute step asm into until the registers have been modified and then do a source step. Or better still, if you know where the jump will go, set a breakpoint in that routine. Example proc stepProc "\ncurrent pc" disasm pc 4 "\nstep by instruction twice" step asm disasm pc 1 step asm disasm pc 1 "\nstep into a procedure call" step into disasm pc 4 "\nstep by statement line twice" step line disasm pc 4 step disasm pc 4 stop end kill 'events' target 'myProg' break \myProg.MAINEVENTLOOP.(11) stepProc launch 'myProg' go #-- output current pc MAINEVENTLOOP +004C 0011F706 486D FFBE **PEA -$0042(A5) +0050 0011F70A 2F0E MOVE.L A6,-(A7) +0052 0011F70C 4EBA FE94 JSR CALLEDPROC ; 0011F5A2 +0056 0011F710 42A7 CLR.L -(A7) step by instruction twice MAINEVENTLOOP +0050 0011F70A 2F0E *MOVE.L A6,-(A7) MAINEVENTLOOP +0052 0011F70C 4EBA FE94 *JSR CALLEDPROC ; 0011F5A2 step into a procedure call CALLEDPROC +0000 0011F5A2 4E56 FFFC *LINK A6,#$FFFC +0004 0011F5A6 2F2D FFE0 MOVE.L -$0020(A5),-(A7) +0008 0011F5AA A873 _SetPort ; A873 +000A 0011F5AC 42A7 CLR.L -(A7) step by statement line twice CALLEDPROC +0004 0011F5A6 2F2D FFE0 *MOVE.L -$0020(A5),-(A7) +0008 0011F5AA A873 _SetPort ; A873 +000A 0011F5AC 42A7 CLR.L -(A7) +000C 0011F5AE A975 _TickCount ; A975 CALLEDPROC +000A 0011F5AC 42A7 *CLR.L -(A7) +000C 0011F5AE A975 _TickCount ; A975 +000E 0011F5B0 2D5F FFFC MOVE.L (A7)+,-$0004(A6) +0012 0011F5B4 42A7 CLR.L -(A7) - Stop -terminate break action Syntax stop Description The Stop command terminates the current break action and returns you to SADE. If the current execution was within a structured statement (Begin...End, for instance), or if multiple commands were selected, the pending commands are executed. To terminate a break action and cancel pending commands, see the Abort command. Example directory 'VolName:Path:toMyProg:' launch 'myProg' proc WhichEvent(stopType) define global EventType[16] := ('null', 'mouse-down','mouse-up', 'key-down', 'key-up','auto-key', 'update', 'disk-inserted','activate', 'network', 'device driver', 'app1',' app2', 'app3', 'app4') if theEvent.what = stopType then printf "%P received, stopping\n", EventType[stopType+1] stop else EventType[theEvent.what+1] printf end end break _waitNextEvent from applzone..applzone^ whichEvent(1) go #-- output key-down update key-down mouse-down received, stopping See also Abort, Break, Quit - Target -tell SADE about your application Syntax target [ progname [ using symbolfilename ] ] Description The Target command tells SADE the name of the application you want to debug; and identifies the symbol file (the .SYM file generated by the linker). If the .SYM file is already in the same directory as the application and is called progname.SYM (which it usually is), you don't need to bother with the using keyword. Progname and symbolfilename are string expressions and must be enclosed in quotes if they are string constants. To find out what the current target is, just type target. Example target "VolName:MPW:MPW Shell" using "VolName:MPW:ToolStuff:tool.sym" sourcePath add "VolName:MPW:ToolStuff:" break \ToolMain.main.(1) launch "mpw shell" #-- Run tool to break to SADE with tool as target #-- and pc at main.(1) - Timer ([n [,bool]]) If no arguments are specified, Timer returns the curretn TickCount. If one argument is specified, then Timer returns TickCount-n (useful for taking the difference between two times). If the bool argument is specified and is non-zero then Timer returns a string of the form "sss.hh" representing seconds and hundreths. If the bool argument is zero then Timer responds as in the one argument case. - Trace -set tracepoints Syntax trace addr ,... or trace trap [ from addr-range ] ,... or trace trap-range [ from addr-range ] ,... or trace all traps [ from addr-range ] or trace class <classname> or trace overload <functionname> Description The Trace command sets tracepoints on the specified address or traps within the target program. Tracepoints can be set on a single trap, a range of traps, or on all traps. Traps can be specified by either trap name or trap number. Trap numbers must be prefixed with the "*" character and trap names must be preceded by an underscore. After setting the tracepoints, you can resume program execution. When the tracepoint is encountered, a message is displayed on standard output, reporting the address or trap being traced, with a symbolic representation of the address if possible. If addr-range is specified, the message is displayed only if the trap was called from the specified memory range. In any case, program execution resumes after the message is displayed. You can specify multiple tracepoints, separated by commas, with a single Trace command. The class keyword is used to set tracepoints on all routines associated with the specified class. The overload keyword is used to set tracepoints on all routines of the specified name in all classes. To remove a tracepoint, use the Untrace command. Example trace _OpenResFile.._GetResource #use a trap range trace *$A997..*$A9A0 #use a trap range See also Untrace - TypeOf (expr) Returns a string with the name (if known) of the type of its expression argument. If the type name is not known then a string of the form "Type #n" is returned, where n is SADE's internal index for that type. - Unbreak -remove breakpoints Syntax unbreak addr ,... or unbreak trap ,... or unbreak trap-range ,... or unbreak all [ traps | addrs ] or unbreak class <classname> or unbreak overload <functionname> Description The Unbreak command clears the breakpoint, as well as any associated break action, for the specified addresses or traps. The all keyword clears all breaks set in the target program. The all keyword can optionally be followed by traps or addrs to restrict the command to traps or addresses respectively. The class keyword is used to clear breakpoints on all routines associated with the specified class. The overload keyword is used to clear breakpoints on all routines of the specified name in all classes. Example unbreak _GetResource #undo break on GetResource trap See also Break - Undef (SADEvar) Returns 1 if the specified SADE var is uninitialized and 0 otherwise. - Undefine -remove definitions Syntax undefine name ,... Description The Undefine command removes the definition; of the specified global SADE variable, procedure, function, or macro. You can supply a list of names to remove multiple definitions. Note that Undefine does not remove local variables defined within SADE procedures or functions. If you want to redefine an item, you don't need to use Undefine; you can just assign a new value to the existing name using the Define command. Example proc ControlledProc printf "%d ", ControllerGlobal end proc Controller define global ControllerGlobal define max := 7 for ControllerGlobal := 1 to max ControlledProc end Undefine ControllerGlobal Undefine ControlledProc end #-- output Controller 1 2 3 4 5 6 7 ControllerGlobal ### Could not find "ControllerGlobal" as a program symbol ControlledProc ### Could not find "ControlledProc" as a program symbol See also Proc, Func, Macro, Define - Untrace -remove tracepoints Syntax untrace addr ,... or untrace trap ,... or untrace trap-range ,... or untrace all [ traps | addrs ] or untrace class <classname> or untrace overload <functionname> Description The Untrace command clears the tracepoint; at the specified addresses or traps. The all keyword clears all tracepoints within the target program. The all keyword can optionally be followed by the traps or addrs keywords to restrict the command to traps or addresses respectively. The class keyword is used to clear tracepoints on all routines associated with the specified class. The overload keyword is used to clear tracepoints on all routines of the specified name in all classes. Example untrace _GetResource #undo trace on _GetResource trap See also Trace - Version -display SADE version information Syntax version Description The Version command displays the current SADE version number. - Where (addr) Returns a string with a symbolic represenation of the specified address (if possible). If SADE is not able to determine a symbolic representation, the hex representation of the address is returned. - While ...End -conditionally repeat commands Syntax while Boolean [ do ] commands end Description The While...End; construct provides conditional looping; with a test at the beginning of the loop. The enclosed commands are executed as long as Boolean is true. If the condition is false at the outset, the enclosed commands are never executed. While constructs may be nested. Example define goSmall := 10 while goSmall > -2 do while goSmall > 4 do while goSmall > 7 do printf " Inner loop - goSmall = %d\n", goSmall goSmall := goSmall -1 end printf " Middle loop - goSmall = %d\n", goSmall goSmall := goSmall - 1 end printf "Outer loop - goSmall = %d\n", goSmall goSmall := goSmall - 1 end #-- output Inner loop - goSmall = 10 Inner loop - goSmall = 9 Inner loop - goSmall = 8 Middle loop - goSmall = 7 Middle loop - goSmall = 6 Middle loop - goSmall = 5 Outer loop - goSmall = 4 Outer loop - goSmall = 3 Outer loop - goSmall = 2 Outer loop - goSmall = 1 Outer loop - goSmall = 0 See also Leave - WindowSize -set the size for new windows or for a 'zoomed' window. Syntax WindowSize Zoom|New [top, left, bottom, right] Description The WindowSize command allows you to set the size and position of newly created windows, and to set the size and postion a window will take when the ZoomWindow button is clicked.